Code
# Load the package
library(ReSources)
# Launch the graphical user interface
ReSources_GUI()Module 3 · Hands-On ReSources Tutorial · 10:45–12:00
One-Day Training Programme | Practical Session 10:45–12:00
This module provides a step-by-step walkthrough of the ReSources graphical user interface (GUI), based on the official ReSources training video. By working through this practical session, you will learn how to:
Ensure you have:
R ≥ 4.0 installed
JAGS ≥ 4.3 installed (download from https://mcmc-jags.sourceforge.io/)
ReSources package installed from GitHub:
devtools::install_github("EISALab/ReSources")Example datasets (available from the ReSources GitHub repository)
# Load the package
library(ReSources)
# Launch the graphical user interface
ReSources_GUI()The ReSources GUI will open in your default web browser. The interface is organized into several tabs:
For this tutorial, we will use the “Five Sources Data Example” included with ReSources.
STEP 1: In the GUI, locate the “Load Example” dropdown menu (typically in the top-left or sidebar)
STEP 2: Select Five Sources Data Example
STEP 3: Click “Load”
This example contains:
Navigate to the Core Model Options tab. This is where you configure the fundamental structure of your mixing model.
ReSources offers five model types (we will not detail all five here, but focus on the most common):
| Model type | Description | When to use |
|---|---|---|
| Independent targets | Each consumer analyzed separately | Standard approach for most archaeological studies |
| Covariate model (categorical) | Group-level effects (e.g., sex, status) | When comparing groups within a population |
| Covariate model (numerical) | Continuous predictors (e.g., age) | When modeling trends with continuous variables |
| Pooled targets | All consumers share a common diet | When assuming population-level homogeneity |
| Hierarchical | Nested structure (e.g., individuals within sites) | Multi-level studies |
For this tutorial: Leave the model type as “Independent targets” (default)
Some input values require a mean and standard deviation (e.g., source isotope values). If you leave the standard deviation blank, ReSources will assign this minimum uncertainty value by default.
Recommended value: 0.1 ‰ for isotope measurements (reflects typical analytical precision)
Components represent the different macronutrient fractions (protein, energy) that contribute differentially to collagen synthesis. Recall from Module 1 that bone collagen carbon is derived ~74% from dietary protein and ~26% from energy sources.
For this tutorial: ✓ Check “Include components” — this is essential for routed mixing models
Concentrations adjust for the fact that different foods have different protein densities. For example:
Without concentration correction, low-protein foods consumed in large quantities may be under-represented in the model.
For this tutorial: ✓ Check “Include concentrations”
Constraint option: ✓ Check “Constrain concentrations 0–100” (ensures percentages remain valid)
ReSources uses a Dirichlet distribution to model the proportional contributions of dietary sources (which must sum to 1). You can choose:
An uninformative prior that treats all sources as equally likely a priori. This is appropriate when you have no strong prior beliefs about dietary composition.
For this tutorial: Select “Optimal objective prior”
Alternatively, you can specify hyperparameters (α values) for the Dirichlet distribution. Higher α values increase the prior weight on a given source.
Example: If historical records suggest heavy reliance on herbivores, you might set:
Bayesian priors should be justified by independent evidence (zooarchaeological abundance, historical texts, ethnohistoric accounts). Unjustified priors can bias results toward preconceived conclusions.
These control the Markov Chain Monte Carlo sampling:
| Parameter | Recommended value | Purpose |
|---|---|---|
| Burn-in steps | 10,000 | Discard initial iterations before chains converge |
| Iterations | 50,000 | Total MCMC samples per chain |
| Thinning | 5 | Keep every 5th sample (reduces autocorrelation) |
| Number of chains | 3 | Run multiple chains to assess convergence |
For this tutorial: Use the default values shown above
Note: Longer chains (100,000+ iterations) are recommended for final publication-quality analyses
Navigate to the Data tab. ReSources organizes input data into five interconnected tables:
This table contains the bone collagen isotope measurements for each individual.
| Column | Description | Example value |
|---|---|---|
| Individual | Unique identifier | “Individual 1” |
| Carbon (mean) | δ13C collagen value (‰) | −19.5 |
| Carbon (SD) | Measurement uncertainty | 0.2 |
| Nitrogen (mean) | δ15N collagen value (‰) | +10.8 |
| Nitrogen (SD) | Measurement uncertainty | 0.3 |
You have three options:
Option 1 — Manual entry:
Click “Add row” and type values directly into each cell
Option 2 — Copy-paste from Excel:
Select cells in Excel → Copy → Click “Paste” button in ReSources (or Ctrl+V)
Option 3 — Import CSV/Excel file:
Click “Import Data” → Select file → Map columns
By default, target values follow a Normal distribution (appropriate for isotope measurements with Gaussian error). Advanced users can select:
For this tutorial: Leave as “Normal” (default)
These are the trophic enrichment factors (Δ13C, Δ15N) that account for isotopic fractionation between diet and consumer tissue. Recall from Module 1 that bone collagen is enriched relative to diet by:
If a consumer is eating herbivores with δ13C = −21 ‰, the consumer’s bone collagen will not be −21 ‰ due to isotopic fractionation. Instead:
\[ \delta^{13}C_{\text{collagen}} = \delta^{13}C_{\text{diet}} + \Delta^{13}C \]
If Δ13C = +1 ‰, then:
\[ \delta^{13}C_{\text{collagen}} = -21 + 1 = -20 \text{ ‰} \]
In the “Target to Source Offset” table, enter:
| Proxy | Offset (mean) | Offset (SD) |
|---|---|---|
| Carbon | +1.0 | 0.3 |
| Nitrogen | +4.0 | 1.0 |
Generic offsets (entered here) apply the same TEF to all dietary sources.
Source-specific offsets allow different TEFs for each source (e.g., Δ15N might be higher for low-protein diets). These are entered in a separate table under “Sources → Source Specific Offsets”.
For most archaeological applications, generic offsets are sufficient.
This is the most complex table in ReSources. It contains the isotope values for each dietary source, separated by component (protein vs. energy).
Because the δ13C of protein in a food is often different from the δ13C of carbohydrates/lipids (energy) in the same food. For example:
| Food | δ¹³C (protein) | δ¹³C (energy) | Difference |
|---|---|---|---|
| Wheat | −26.5 ‰ | −25.8 ‰ | 0.7 ‰ |
| Cattle meat | −21.3 ‰ | −22.0 ‰ | −0.7 ‰ |
| Marine fish | −14.8 ‰ | −15.2 ‰ | −0.4 ‰ |
For each dietary source, you must enter:
Carbon proxy:
| Source | Protein (mean) | Protein (SD) | Energy (mean) | Energy (SD) |
|---|---|---|---|---|
| Herbivores | −21.3 | 0.7 | −22.0 | 0.9 |
| Carnivores | −19.5 | 0.8 | −20.1 | 1.0 |
| Plants | −26.8 | 1.2 | −25.8 | 0.9 |
| Fish 1 | −24.2 | 1.3 | −24.5 | 1.4 |
| Fish 2 | −23.8 | 1.1 | −24.0 | 1.2 |
Nitrogen proxy:
| Source | Protein (mean) | Protein (SD) |
|---|---|---|
| Herbivores | +6.8 | 1.1 |
| Carnivores | +9.2 | 1.3 |
| Plants | +3.5 | 1.5 |
| Fish 1 | +12.5 | 1.6 |
| Fish 2 | +11.8 | 1.4 |
Because nitrogen is essentially absent from carbohydrates and lipids. Collagen nitrogen is derived 100% from dietary protein, so we only need the protein component for δ15N.
Source isotope values must come from:
This table defines how much of the collagen signal comes from dietary protein vs. energy (carbohydrates + lipids).
Recall from Module 2 the routed mixing equation:
\[ \delta^{13}C_{\text{collagen}} = \lambda \cdot \delta^{13}C_{\text{protein}} + (1 - \lambda) \cdot \delta^{13}C_{\text{energy}} \]
Where λ (lambda) is the routing parameter. For human bone collagen:
| Proxy | Protein (mean) | Protein (SD) | Energy (mean) | Energy (SD) |
|---|---|---|---|---|
| Carbon | 0.74 | 0.08 | 0.26 | 0.08 |
| Nitrogen | 1.00 | 0.00 | 0.00 | 0.00 |
Interpretation:
Imagine a diet with:
Unrouted model (SIAR, early MixSIAR) would predict: \[ \delta^{13}C_{\text{collagen}} = 0.70 \times (-12) + 0.30 \times (-21) = -14.7 \text{ ‰} \]
Routed model (ReSources) with λ = 0.74: \[ \begin{aligned} \delta^{13}C_{\text{protein}} &= -21 \text{ ‰} \\ \delta^{13}C_{\text{energy}} &= -12 \text{ ‰} \\ \delta^{13}C_{\text{collagen}} &= 0.74 \times (-21) + 0.26 \times (-12) = -18.7 \text{ ‰} \end{aligned} \]
The 4 ‰ difference is substantial! Without routing, you would overestimate maize contribution.
This table records the nutrient density (% protein, % energy) of each dietary source. This is necessary because:
A consumer eating 1 kg of plants vs. 1 kg of meat is consuming different amounts of protein, even though the mass is equal.
| Source | Protein (mean) | Protein (SD) | Energy (mean) | Energy (SD) |
|---|---|---|---|---|
| Herbivores | 20.0 | 2.0 | 10.0 | 1.5 |
| Carnivores | 22.0 | 2.5 | 15.0 | 2.0 |
| Plants | 8.0 | 1.5 | 70.0 | 5.0 |
| Fish 1 | 18.0 | 2.0 | 8.0 | 1.5 |
| Fish 2 | 19.0 | 2.2 | 9.0 | 1.8 |
Interpretation:
If unavailable, use standard values from nutritional references, but report this assumption.
Concentrations can follow:
For this tutorial: Leave as “Normal” (default)
Before running the MCMC, it’s good practice to visualize the mixing space and check whether your model is well-posed.
Navigate to the Model Characteristics tab.
This tool simulates what consumer isotope values would look like if they consumed 100% of a single source.
STEP 1: Click “Run Simulation”
STEP 2: Wait ~10–30 seconds while ReSources calculates expected ranges
STEP 3: View the 2D plot (if you have 2 proxies: carbon + nitrogen)
The plot shows:
✓ Consumers fall inside the mixing polygon — good! The model is feasible.
✗ Consumers fall outside the polygon — problem! Either:
Action: Revisit your source list and TEF assumptions.
You can also simulate specific dietary scenarios. For example: “What if someone ate 50% herbivores and 50% carnivores?”
STEP 1: Enter proportions in the “Source Contributions” boxes:
STEP 2: Click “Simulate”
STEP 3: The predicted consumer values appear as a point on the plot
You are now ready to execute the Bayesian MCMC simulation.
STEP 1: Navigate to the top of the interface (usually a button labeled “Run Model” or “Execute”)
STEP 2: Click “Run Model”
STEP 3: Wait for:
Total time: 2–5 minutes for this example (larger models take longer)
Small models (≤10 consumers): FRUITS is faster (no compilation step)
Large models (50+ consumers): ReSources is faster (more efficient MCMC sampler)
After the model runs, ReSources automatically checks convergence using the Gelman-Rubin statistic (\(\hat{R}\)).
✓ \(\hat{R} < 1.1\) for all parameters → chains have converged (good!)
✗ \(\hat{R} > 1.1\) for some parameters → chains have not mixed properly (bad!)
If convergence fails:
A summary message will display:
“ReSources run: 1 Monte Carlo chain, 10000 burning steps, 50000 draws, thinning = 5. Model: Independent targets. Convergence diagnostic (Geweke): No convergence failures.”
Navigate to the Results tab.
The Results Report table displays posterior summaries for all estimated parameters.
| Source | Individual | Estimate Type | Mean | SD | 2.5% | 97.5% | p-value |
|---|---|---|---|---|---|---|---|
| Herbivores | Individual 1 | target | 0.42 | 0.12 | 0.18 | 0.65 | 0.032 |
| Carnivores | Individual 1 | target | 0.15 | 0.09 | 0.02 | 0.35 | 0.187 |
| Plants | Individual 1 | target | 0.23 | 0.11 | 0.05 | 0.46 | 0.098 |
| Fish 1 | Individual 1 | target | 0.12 | 0.08 | 0.01 | 0.31 | 0.245 |
| Fish 2 | Individual 1 | target | 0.08 | 0.07 | 0.00 | 0.25 | 0.412 |
Interpretation:
Wide intervals (e.g., [0.05, 0.85]) reflect genuine uncertainty due to:
This is honest reporting, not model inadequacy.
STEP 1: Select desired estimate type from dropdown (e.g., “Source contributions”)
STEP 2: Click “Export”
STEP 3: Choose format:
Navigate to Results → Results Plots.
Shows all individuals for a single dietary source.
STEP 1: Select “Display by: Estimate”
STEP 2: Select “Source contributions” from estimate type dropdown
STEP 3: Select “Herbivores” from source dropdown
STEP 4: View boxplots showing herbivore contributions for all individuals
Interpretation:
Shows all dietary sources for a single individual.
STEP 1: Select “Display by: Target”
STEP 2: Select “Individual 1” from target dropdown
STEP 3: View boxplots comparing all five sources for that individual
If you included categorical covariates (e.g., sex, burial context, time period), you can compare group-level estimates.
Example: Do males and females have different herbivore consumption?
STEP 1: Select “Covariate: Sex”
STEP 2: Select “Herbivores” as source
STEP 3: Compare boxplots for males vs. females
Statistical test: Check if 95% CIs overlap. If they do not overlap, there is strong evidence for a difference.
You can create custom dietary groupings by combining sources.
Suppose you want to know the total contribution of all animal protein (herbivores + carnivores + fish):
STEP 1: Navigate to “User Estimates” tab
STEP 2: Click “Add New Estimate”
STEP 3: Enter name: Total_Meat
STEP 4: Select sources to include:
STEP 5: Check “Normalize” (ensures Total_Meat + Plants = 100%)
STEP 6: Click “Apply”
The new estimate Total_Meat now appears in the results tables and plots.
You can impose inequality constraints based on prior knowledge.
If zooarchaeological evidence suggests herbivore bones outnumber carnivore bones 3:1, you might constrain:
\[ \text{Herbivores} > \text{Carnivores} \]
STEP 1: Navigate to “User Estimates” → “Constraints”
STEP 2: Select “Herbivores” from dropdown 1
STEP 3: Select “>” (greater than)
STEP 4: Select “Carnivores” from dropdown 2
STEP 5: Optionally add uncertainty to this constraint (softens it from a hard rule to a probabilistic prior)
STEP 6: Click “Add Constraint”
Constraints should be based on independent archaeological evidence, not circular reasoning. Document your justification clearly in publications.
Navigate to Model Diagnostics tab.
Trace plots show the MCMC chain history for each parameter. Good convergence looks like:
✓ “Hairy caterpillar” — rapid mixing across the parameter space
✗ Trending — chain is still “burning in” (increase burn-in)
✗ Stuck — chain is trapped in a local mode (increase iterations; check for non-identifiability)
STEP 1: Select “Trace Plot” from diagnostic dropdown
STEP 2: Select “Source contributions” → “Herbivores” → “Individual 1”
STEP 3: Examine the plot for all 3 chains (should overlap and mix well)
For each parameter, \(\hat{R}\) compares within-chain variance to between-chain variance:
Navigate to Goodness of Fit Tests → Convergence Tests → View \(\hat{R}\) values
ESS measures how many independent samples your MCMC chains produced (after accounting for autocorrelation).
Navigate to Goodness of Fit Tests tab.
For each consumer, ReSources calculates a Bayesian p-value that tests:
“How probable is the observed consumer isotope value given the posterior dietary estimates?”
If several individuals have extreme p-values:
Deviance Information Criterion (DIC) and Widely Applicable Information Criterion (WAIC) allow you to compare alternative models:
| Model variant | DIC | WAIC | Preferred? |
|---|---|---|---|
| 5 sources, routed | 245.3 | 248.1 | ✓ |
| 5 sources, unrouted | 312.7 | 315.4 | ✗ |
| 4 sources (fish pooled) | 248.9 | 251.2 | ~ |
Rule: Lower DIC/WAIC = better model fit. Differences of >10 are considered substantial.
Cause: Data inconsistency (e.g., proxy names don’t match between tables)
Fix: Check that “Carbon” and “Nitrogen” are spelled identically in:
Cause:
Fix:
Cause: You allowed Normal distributions for concentrations, which can sample negative values
Fix: Check “Constrain concentrations 0–100” in Core Model Options
By the end of this hands-on session you should be able to:
flowchart TD
A[1. Load ReSources GUI] --> B[2. Configure Core<br/>Model Options]
B --> C[3. Enter Target<br/>consumer data]
C --> D[4. Enter Target to Source<br/>Offset TEFs]
D --> E[5. Enter Sources<br/>food isotope values]
E --> F[6. Enter Components<br/>routing weights]
F --> G[7. Enter Concentrations<br/>nutrient densities]
G --> H[8. Visualize Mixing Space<br/>Model Characteristics]
H --> I{Data valid?}
I -->|No| J[Revise sources<br/>or TEFs]
J --> C
I -->|Yes| K[9. Run MCMC<br/>Bayesian simulation]
K --> L[10. Check Convergence<br/>Gelman-Rubin Rhat]
L --> M{Converged?}
M -->|No| N[Increase iterations<br/>or pool sources]
N --> K
M -->|Yes| O[11. Interpret Posteriors<br/>means, CIs, p-values]
O --> P[12. Create User Estimates<br/>custom groupings]
P --> Q[13. Export Results<br/>Excel/CSV/JSON]
Q --> R[14. Publication]
style A fill:#D6ECEE
style K fill:#FFF3DF
style O fill:#C1E1C1
style R fill:#E8F5E9End of Module 3 — Lunch break 12:00–13:00
Afternoon session continues with archaeological case studies and publication-ready analyses